Partners

A API Partners permite a gestão dos parceiros cadastro, consultas, extratos de comissões e afins.

Pré-requisitos

Antes de começar a utilizar a API, é fundamental compreender os requisitos de autenticação e obter as credenciais necessárias.
Certifique-se de revisar a seção de autenticação para garantir uma integração segura e bem-sucedida.

Demonstrativos e extratos de comissões.

Permite obter os demonstrativos e extratos de comissões dos parceiros.

Requisição (Request)

Url	https://api-sandbox.pottencial.com.br/partners/v1/partners/commission-statement
Method	Get
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Query	statementStartDate	Filtro por período demonstrativo inicial (emissão) do evento.	string (date)
	statementEndDate	Filtro por período demonstrarivo.	string (date)

Respostas (Response)

Status	Descrição	Tipo
200	Lista de emissão do demonstrativo de comissões.	CommissionStatements
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
403	Parceiro não autorizado a realizar a operação.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Obs. O campo paidDate pode retornar null quando o status da comissão for diferente de "PAGO"

Exemplo

[
  {
    "irrfAmount": "14781.62",
    "issAmount": "150000",
    "pisAmount": "0",
    "cofinsAmount": "50",
    "csllAmount": "0",
    "netAmount": "15000",
    "totalCommission": "1000",
    "statementNumber": "4300",
    "status": "PAGO",
    "paidDate": "2020-02-11",
    "items": [
      {
        "policyType": "E1",
        "endorsementType": "E2",
        "customerName": "Nome do Cliente",
        "customerDocumentNumber": "1111111",
        "policyNumber": "010101010",
        "endorsementNumber": "210202020",
        "proposalNumber": "2222222",
        "groupLine": "0775",
        "installmentNumber": "1",
        "commercialPremium": "140",
        "commissionPercentage": "25",
        "brokerCommissionPercentage": "100",
        "commissionAmount": "25.5",
        "commissionType": "Tipo  A",
        "status": "P",
        "eventDate": "2020-01-11",
        "releaseDate": "2020-02-11",
        "eventType": "TIPO EVENTO"
      }
    ]
  }
]

Consultar as licitações associadas aos clientes do parceiro.

Permite obter as licitações, com participação dos clientes do parceiro, gerando oportunidades de negócios para contratação através do produto Garantia do Licitante (BID) .

A Pottencial disponibiliza dados de licitações e associa automaticamente a licitação ao cliente do parceiro, fornecendo o acesso por API.

Requisição (Request)

Url	https://api-sandbox.pottencial.com.br/partners/v1/partners/opportunities
Method	Get
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Query	PolicyHolderDocument	Filtro por cnpj/cpf dos clientes dos parceiros.
Query	CreatedAt	Data de inclusão.
Query	Take	Quantidade de registro nas requisição.
Query	Skip	Pagina da requisição.

Respostas (Response)

Status	Descrição	Tipo
200	Lista de oportunidades das licitações.	Oportunidades
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
403	Parceiro não autorizado a realizar a operação.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

{
  "totalPages": "10",
  "totalOpportunities": "150",
  "opportunities": [
    {
      "policyHolderName": "Nome tomador",
      "policyHolderDocument": "22222222222222",
      "insuredName": "Nome do Beneficiario",
      "insuredDocument": "11111111111111",
      "insuredState": "MG",
      "insuredCity": "Belo Horizonte",
      "competitionStartDate": "2022-09-01",
      "biddingObject": "descricao da oportunidade",
      "insuredAmount": "15000",
      "biddingLink": "https://oportunidades.com.br",
      "createdAt": "2022-09-01"
    },
    {
      "insuredName": "Nome tomador 2",
      "insuredDocument": "33333333333",
      "policyHolderName": "Nome do Beneficiario",
      "policyHolderDocument": "44444444444444",
      "insuredState": "MG",
      "insuredCity": "Belo Horizonte",
      "competitionStartDate": "2022-09-10",
      "biddingObject": "descricao da oportunidade 2",
      "insuredAmount": "55000",
      "biddingLink": "https://oportunidades2.com.br",
      "createdAt": "2022-09-11"
    }
  ]
}

Consultar as licitações disponíveis.

Permite obter as licitações, para oportunidades ainda não associadas a qualquer parceiro, possibilitando a contratação através do produto Garantia do Licitante (BID) .

A Pottencial disponibiliza dados de licitações em ambito geral, fornecendo o acesso por API.

Requisição (Request)

Url	https://api-sandbox.pottencial.com.br/partners/v1/partners/biddings
Method	Get
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Query	MaxCompetitionStartDate	filtro por data minima do certame.
Query	MinCompetitionStartDate	filtro por data minima do certame.
Query	MaxInsuranceAmount	filtro por valor maximo segurado.
Query	MinInsuranceAmount	filtro por valor minimo segurado.
Query	Skip	pagina da requisição.
Query	Take	quantidade de registro nas requisição.

Respostas (Response)

Status	Descrição	Tipo
200	Lista de oportunidades das licitações.	Biddings
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
403	Parceiro não autorizado a realizar a operação.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

{
  "totalPages": "23",
  "totalBiddings": "550",
  "biddings": [
    {
      "insuredAmount": "22000.55",
      "competitionStartDate": "2022-09-01",
      "insuredName": "Nome do Beneficiario",
      "insuredDocument": "11111111111111",
      "insuredState": "MG",
      "insuredCity": "Belo Horizonte",
      "biddingObject": "descricao da oportunidade"
    },
    {
      "insuredAmount": "75100.20",
      "competitionStartDate": "2022-09-01",
      "insuredName": "Nome do Beneficiario",
      "insuredDocument": "22222222222222",
      "insuredState": "MG",
      "insuredCity": "Belo Horizonte",
      "biddingObject": "descricao da oportunidade 2"
    }
  ]
}

Consulta de Corretoras

Fornece informações detalhadas sobre como verifique as corretoras cadastradas na Pottencial e a sua elegibilidade para ser utilizada nas jornadas de contratação e co-corretagem. Inclui endpoints disponíveis, parâmetros de consulta e exemplos de solicitação e resposta.

Corretora com status inativa:
Se ao pesquisar uma corretora e o retorno estiver com status "Inativa", isso indica que a corretora não está habilitada para realizar cotações e/ou ser utilizada em co-corretagem. Portanto, cotações e emissões de apólices não podem ser realizadas através desta corretora. Recomenda-se aos parceiros que estejam com o status "Inativa" a regularizar o seu cadastro perante a SUSEP.

Requisição (Request)

Url	https://api-sandbox.pottencial.com.br/partners/v1/commission-agents/brokers
Method	Get
Headers	client_id	Client ID da App.
	access_token	Token de acesso gerado para a App.
Query	DocumentNumbers	filtro por CNPJ/CPF do corretora.	array (string)

Respostas (Response)

Status	Descrição	Tipo
200	Lista de informações do parceiro.	PartnerBrokers
400	Os dados da requisição estão inválidos.	ErrorResult
401	Parceiro não autorizado a realizar a operação.	ErrorResult
403	Parceiro não autorizado a realizar a operação.	ErrorResult
500	Erro interno da API. Por favor tente novamente mais tarde ou contate o suporte técnico da Pottencial.	ErrorResult

Exemplo

[
  {
    "Name": "Corretora ABC",
    "DocumentNumber": "01063414059",
    "SUSEPNumber": "123456",
    "Status": "Active",
    "Products": [
      "residencial",
      "judicial-deposito-recursal",
      "imobiliario"
    ]
  },
  {
    "Name": "Corretora XPTO",
    "DocumentNumber": "90455292000140",
    "SUSEPNumber": "654321",
    "Status": "Inactive",
    "Products": [
      "judicial-civel",
      "vida",
      "empresarial"
    ]
  }
]

Dicionario

CommissionStatement

Campo	Tipo	Regras	Descrição
CommissionStatement
irrfAmount	number	Opcional	Imposto de Renda Retido na Fonte .
issAmount	number	Opcional	Imposto Sobre Serviços (Imposto Municipal).
pisAmount	number	Opcional	Programa de Integração Social (Imposto Federal)
cofinsAmount	number	Opcional	Contribuição para Finaciamento da Seguridade Social (Imposto Federal ).
csllAmount	number	Opcional	Contribuição Social sobre Lucro Liquido (Imposto Federal).
netAmount	number	Opcional	Valor Liquido.
totalCommission	number	Opcional	Valor total da Comissão.
statementNumber	number	Opcional	Numero do demonstrativo.
status	string	Opcional	Status.
items	array de Item	Opcional	Lista das ápolices contidas no demostrativo.
Item
policyType	string	Opcional	Tipo Apolice.
endorsementType	string	Opcional	Tipo Endosso.
customerName	string	Opcional	Nome do cliente.
customerDocumentNumber	string	Opcional	Cpj ou Cnpj do cliente.
proposalNumber	string	Opcional	Numero da proposta.
policyNumber	string	Opcional	Numero da apolice.
endorsementNumber	string	Opcional	Numero do Endosso.
groupLine	string	Opcional	identificador do Grupo e Ramo.
installmentNumber	number	Opcional	Numero da parcela.
commercialPremium	number	Opcional	Valor prêmio comercial.
commissionPercentage	number	Opcional	Porcentagem de comissão.
brokerCommissionPercentage	number	Opcional	Porcentagem de comissão da Corretora.
commissionAmount	number	Opcional	Valor do premio liquido .
commissionType	string	Opcional	Tipo de Comissão.
status	string	Opcional	Status.
eventDate	string (date-time)	Opcional	Data do evento.
releaseDate	string (date-time)	Opcional	Data de lançamento.
eventType	string	Opcional	Tipo de evento.
ErrorResult
errors	array de ErrorMessage	Opcional	Lista de erros da solicitação.
ErrorMessage
code	string	Opcional	Código de identificação do erro.
message	string	Opcional	Descrição do erro.

Oportunidades

Permite obter a listagem das oportunidades das licitações

Campo	Tipo	Regras	Descrição
totalPages	number	Somente leitura	Total de paginas .
totalOpportunities	number	Somente leitura	Total de oportunidades .
opportunities	array de Oportunidade	Opcional	Lista de oportunidades .

Oportunidade

demonstrativo de Oportunidade

Campo	Tipo	Regras	Descrição
policyHolderName	string	Somente leitura	Nome do Tomador.
policyHolderDocument	string	Somente leitura	Cnpj/ Cpf do Tomador.
insuredName	string	Somente leitura	Nome do beneficiario.
insuredDocument	string	Somente leitura	Cnpj/ Cpf do beneficiario .
insuredState	string	Somente leitura	Estado federal do segurado.
insuredCity	string	Somente leitura	Cidade do segurado.
competitionDate	string (date)	Somente leitura	Data inicio do certame.
biddingObject	string	Somente leitura	Descrição da licitação.
insuredAmount	number	Somente leitura	valor da licitação.
biddingLink	string	Somente leitura	link da licitação.
createdAt	string (date)	Somente leitura	Data de inclusão do registro.

Biddings

Permite obter a listagem das licitações

Campo	Tipo	Regras	Descrição
totalPages	number	Somente leitura	Total de paginas .
totalBiddings	number	Somente leitura	Total de licitações.
biddings	array de Bidding	Opcional	Lista de licitações .

Bidding

demonstrativo de licitações

Campo	Tipo	Regras	Descrição
insuranceAmount	string	Somente leitura	Valor da licitação.
competitionDate	string (date)	Somente leitura	Data de inicio do certame.
insuredName	string	Somente leitura	Nome do beneficiario .
insuredDocument	string	Somente leitura	Cnpj/ Cpf do beneficiario .
insuredState	string	Somente leitura	Estado federal .
insuredCity	string	Somente leitura	Cidade .
biddingObject	string	Somente leitura	Descrição da licitação .

PartnerBrokers

Dados do Corrtor

Campo	Tipo	Regras	Descrição
Name	string	Somente leitura	Nome do Corretor.
DocumentNumber	string	Somente leitura	CPF/ CNPJ do Corretor.
SUSEPNumber	string	Somente leitura	Numero de registro na SUSEP.
Status	string (BrokerStatus)	Somente leitura	Situação atual do Corretor.
Products	Somente leitura	Produtos que o Corretor está habilitado e registrado na SUSEP e liberados para comercialização na Pottencial.

BrokerStatus

Situação do parceiro.

• Active:Parceiro ativo.
• Inactive: Parceiro inativo.

Resolução de erros

Código	Erro	Descrição	Solução
400	Bad Request	Invalid secret in Authorization header	O client_secret informado no header é inválido. Verifique se o client_secret informado é o mesmo da APP e se o header Authorization está sendo passado conforme especificado.
401	Unauthorized	Could not find a required APP in the request, identified by HEADER client_id.	O client_id informado no header é inválido. Verifique se o client_id informado é o mesmo da APP e se o header Authorization está sendo passado conforme especificado.
404	Not Found	Not Found	Provavelmente a URL sendo chamado não está correta. Verifique se está conforme especificado.
500	Internal Server Error	Internal Server Error	Erro não esperado, algo está quebrado na API. Por favor aguarde ou entre em contato com o time de suporte.

Estrutura da mensagem de erro

ErrorResult

Representa um resultado de erro na chamada da plataforma.

Campo	Tipo	Regras	Descrição
errors	array de ErrorMessage	Opcional	Lista de erros da solicitação.

ErrorMessage

Contém informações de um erro.

Campo	Tipo	Regras	Descrição
code	string	Opcional	Código de identificação do erro.
message	string	Opcional	Descrição do erro.